Am 19.05.2011 05:06, schrieb SGeier:

>> clipped_by is implemented as follows:
>>
>> (1) The base object's intersection(s) with the ray are determined;
>>
>> (2) for each intersection it is checked whether it is inside the
>> clipped_by object.
>>
>> Any intersections not reported by step (1) are ignored.
>
> Good to know that this is how it is implemented. However this is NOT how it
> is documented. Put the above paragraph into the documentation and
> implementation and documentation are in agreement.

If you think the documentation is bad, then you're happily invited to 
help make it better.

It's not like the developers & other people helping with POV-Ray would 
be paid anything for it; our only payment is the joy of doing it (and 
every programmer knows that implementation work is more fun than writing 
documentation), the joy of seeing people get good results of it, and the 
joy of receiving some motivating feedback from the community now and then.

So if you /want/ anything from us, or want to /insist/ on some point of 
view that the dev team does not share, you're in the wrong place.

> I would hope so - that's why I post things here that do not work as
> documented.

It's one thing to get feedback on things that people /think/ is wrong. 
Getting feedback from someone who /knows better/ (or at least sounds 
like that) is something entirely different.

> There's a perennial communications problem between programmers and users: To
> the programmer, the code is the end-all and be-all. Whatever the code does
> is "true" and if the documentation deviates from it, then the documetation
> is wrong. However from the user perspective, the documentation is all there
> is - it tell me what is *supposed* to happen and if the observed results are
> different then the code is buggy.

No. To the programmer, the /intention/ is the end-all and be-all. If the 
code fails to match that, it is buggy. If the documentation fails to 
match that, it is either wrong (making an explicit statement that is not 
true), incomplete (failing to make an explicit statement that is true 
bot not necessarily obvious to the user), or imprecise (making a 
statement that can be interpreted in a way that is true, but also in 
another way that is not).

In this particular case, the documentation is /incomplete/, but not 
wrong: It does /not/ make an explicit statement about the situation you 
encountered. It does however make a statement about similar situations 
with CSG, which /might/ give resourceful users a hint what's going wrong 
with regard to clipped_by.


BTW, to the end user, the /expectation/ is the end-all and be-all; the 
documentation can only serve to modify those expectations. So if some 
docs do not explicitly mention the program's behaviour in a very rare 
situation, who is outright /wrong/: The documentation, or the user's 
expectations? I dare say the latter, because the docs simply cannot 
foresee all that a user may expect.

Also note that in real life there is no such thing as a /complete/ 
documentation.

> If the wording in the docs leads the reader to expect behaviour different
> from what is implemented, then the wording is far enough from ideal that we
> might as well call it false.

I disagree in some points:

(1) The docs do not /lead/ the reader to expect behaviour different from 
what is implemented in this case. It is /your/ expectation, and all you 
can blame the documentation for is that it did not /lead you away/ from 
that expectation. Provided that you even gave it a chance to do so, by 
thoroughly reading the isosurfaces doc section.

(2) I guess that careful reading of the doc section on isosurfaces 
/will/ lead the majority of readers away from that expectation, at least 
to the degree that they're not too surprised when their original 
expectation proves wrong.

(3) My definition of a "false" documentation is more strict than yours 
seems to be. In my terminology, "incomplete" or "imprecise" is not 
necessarily "false".


> If that is "as intended", then this intention needs to be communicated (in
> the docs, not here).

(4) There is no /need/ to communicate the programmers' intentions to the 
users. It's probably /helpful/, but there is no such /obligation/ to the 
dev team - neither legally (see the license) nor morally (what you get 
from the dev team is a free gift, and you can either take it or leave 
it, and there's nothing you can /demand/ on top).

Post a reply to this message